Concepts - Report processing variables

Introduction

Report processing (“Actions to take”) occur on the magic5 server at various points in a form’s life cycle and on the device itself when the form is finished. As magic5 evolves, this list might change so contact magic5 support for further information.

Fields common to all actions

Description	A brief description of the action, used to help identify the action.
Allow user to choose to run this action	For device-based actions this option allows you to specify whether the action happens automatically when a form is released (in which case the user has no control over it) or whether the user is given the choice of running the action manually.
Conditions (Advanced tab)	Restricts action to running only under certain conditions. Further information on this is available at Reference - Conditions

Any items marked with a red asterisk (*) are mandatory and must be completed before saving the template.

Report processing variables

Many fields associated with report processing can make use of Report processing variables, especially those relating to the text of e-mails or file names to be generated. This means that the text “This is a report for %CUSTOMER%” will have the text ‘%CUSTOMER%’ replaced with the actual customer name entered on the device (eg Mr Smith) to generate the text "This is a report for Mr Smith" in the final report.

Report Processing Variables must have both a leading and trailing “%” (eg "%LOCATION%")and, as they are case-sensitive must be entered EXACTLY as shown in the list below (eg "%Year%" will NOT be correctly interpreted).

Fields which accept Report Processing Variables can accept any number of them in any order and any number of iterations. Any text which is not recognized as a Report Processing Variable is left as-is.

The full list of variables:

CUSTOMER	Customer name
LOCATION	Location name
DATE	The date/time of the form in the format YYYYMMDD”T”HHMMSS
SHORT_DATE	The date part of DATE: YYYYMMDD
YEAR	The year part of DATE: YYYY
MONTH	The month part of DATE: MM
WEEK_SUNDAY	The Sunday starting the week of DATE: YYYYMMDD
WEEK_MONDAY
GUID	The unique ID given to the report. For example, FD8DFE2D-33A7-4761-A1E8-4448DE4C1541
REPORT_URL	The full web link that gives a points to the report
INSTALL_NAME	The name for this installation of magic5
CURRENT_DATE	The current date/time in the format YYYYMMDD”T”HHMMSS
CURRENT_SHORT_DATE	The date part of CURRENT_DATE: YYYYMMDD
CURRENT_YEAR	The year part of CURRENT_DATE: YYYY
CURRENT_MONTH	The month part of CURRENT_DAT : MM
CURRENT_WEEK_SUNDAY	The Sunday starting the week of CURRENT_DATE: YYYYMMDD
CURRENT_WEEK_MONDAY	The Monday starting the week of CURRENT_DATE: YYYYMMDD
USERFULLNAME	The first name and last name of the user completing the form
$customer	Customer name (backwards compatible)
$location	Location name (backwards compatible)
@xxxx	The value, in the current form, of the item with unique name ‘xxxx’. A unique name is specified for all entry items within a template and this option allows the value entered on the device to be output as part of the action.

The WEEK_SUNDAY and WEEK_MONDAY variables can be used, for example, in outputting to files or directories which will contain all data for a specified week. The use of Sunday or Monday simply enables a choice of when the week is designated to begin. In the case of producing monthly or yearly outputs, YEAR and MONTH are sufficient.

Root output directory

Any files created by report processing (for example, Access databases or XML files) will be created underneath the “Root Output Directory”. This location of this directory is held within the TargetInstance/RootOutputDirectory setting of the magic5Workflow.exe.config file. In addition, there will individual sub-directories of this root for each of the “data organisations” set up on the system. In practice this simply means that your own files will be under the “2” sub-directory of the root. When specifying the output file name and location, bear in mind that the location will be relative to this root.

Server actions

Actions are triggered on the magic5 server:

When a report is received from the Device (Incomplete or Complete)	This action is triggered when a report is sent from the device to the server, regardless of it's status. All the actions described below are available.
When a report becomes available for sign-off (Complete)	This action is triggered when the report is marked as complete on the server, but before it is signed-off. All the actions described below are available.
When a report is signed-off to the customer (Released)	This action is triggered when the report is signed-off on the server. All the actions described below are available.
When an interim report is received	This action is triggered when an interim report is received on the server. An interim report is generated as a snapshot on a device which can alert the server that a certain stage has been reached (eg a job started, an emergency light activated, a customer notified). These interim events can happen within a form and when the whole form is complete it will go through the usual actions as above. All the actions described below are available.

These actions are processed by the Windows Service “magic5 Workflow Engine”.

Export to Access 2003 database

The “export to Access” option exports all of the data captured on a form into Access database tables. The “unique names” defined for documents and for individual items are used to generate and update the Access tables. One Access table is created for each document, and the name of the table is the unique name of the document. For each individual item, a field is created within the table, the field name being the unique name of the item. In addition to these variable aspects of the template, fields are also created for the customer, location, date etc. Further to this, tables are also created within the Access database to hold values for general purpose lists, for customers, locations, templates etc.

The database name can contain “Report processing variables”. This means that you can have multiple databases being created for each template. For instance, you could have one database per month, per day, per week, per customer etc.

Access database location and file name

The file name (and possibly path) to the Access database to be created and exported to. Any files created will be located under the “Root Output Directory”. This means that you should not specify a drive name, simply a path under the Root Output Directory. Any folder specified does not have to exist, and the database itself will be created by magic5 automatically. This field allows “Report processing variables”.

Use text of list entries rather than list entry id (useful if you have many different list items)

By default magic5 will output its own internal ‘id’ for a given list item, together with an Access database table containing the “text” corresponding to this id. In general this is the “correct” way of dealing with database data and it avoids duplication of data. However, if you wish to use text values directly for the sake of simplicity then you can enable this option. There are also limits within Access itself in terms of how many items within a database table can be cross-referenced with a “lookup” table – if such a limit is reached then this option can be used to revert to simple text values.

E-mail a PDF version of the report

E-mail address to send report to	Enter the e-mail address of the person you wish the report to be sent to. This should be a valid SMTP e-mail address such as somebody@company.com. Note that you can enter multiple addresses, separated by semi-colons.
E-mail all customer-wide contacts	magic5 allows contacts to be added to a customer rather than a location. These are called customer-wide contacts. If this option is selected then the report will be e-mailed to any and all customer-wide contacts for the customer.
E-mail to all contacts for location	If this option is selected then the report will be e-mailed to all contacts for the location of the report.
E-mail all addresses specified in ‘E-mail Address’ template items	If you have an “e-mail address” item within your template (allowing the user to input a customer’s e-mail address for example) then selecting this option will cause the report to be e-mailed to addresses specified in this way.
E-mail the user who completed the form	Select this option to e-mail a report to the address set up for the person currently logged onto the device. See Users for more details.
E-mail addresses specified in template items (enter 'unique names' separated by commas)	This text box allows e-mail addresses that have been collected in non-email specific template items (and therefore unvalidated) to be sent copies of the report. More than one unique item name can be entered here, separated by commas. This facility is primarily used for imported data.
E-mail address to send report from	Enter the e-mail address to be shown as having sent the report e-mail. This will also be the e-mail address that any reply is sent to. This field allows “Report processing variables”. If no value is specified the default will be used.
Subject line of e-mail	Enter the subject line for the e-mail. This field allows “Report processing variables”. If no value is specified the default will be used.
Text of e-mail	Enter the body text for the e-mail. This field allows “Report processing variables” If no vHTMLlue is specified the default will be used.
E-mail attachment name
Include additional attachments of photos etc. separately within e-mail	Select this option to include photos in addition to those included in the PDF report. They will be sent as extra attachments
Prefix for additional attachment names	Prefix for the above - eg "Photo" entered here would generate attachments titled Photo1, Photo2, Photo3, etc.

Output to XML file

This option outputs results to an XML file. Typically this is used for communicating results to third party systems. Full details on the file structure are contained within the “Interfacing External Systems to ” document.

Output directory	The directory that will contain the XML output files. Note that this directory will be underneath the “Root Output Directory”, so here you simply need to specify the relative path (eg. “XYZ System Output”). Any folder specified does not have to exist. This field allows “Report processing variables”.
Output ‘lookup’ information (lists, users, customers, locations etc.)	If “lookup” values such as list entries, usernames, customers and locations have been created within magic5 (and not imported from a third party system) then this option allows these lookup values to be output along with the form data.

Output to PDF file

This option outputs results to a PDF document. The PDF created is the same as for the “E-mail a PDF version of the report” action, but is output to a file on the server rather than as an attachment to an e-mail.

Output directory

The directory that will contain the PDF output files. Note that this directory will be underneath the “Root Output Directory”, so here you simply need to specify the relative path (eg. “XYZ System Output”). Any folder specified does not have to exist. This field allows “Report processing variables”.

Output to CSV file

CSV location and file name	This field allows “Report processing variables”.
CSV transformation	'None' and 'Standard CSV' are supplied as standard with which means that everything gets output into it's own field in the CSV file. Alternative formats need to be discussed with our support team, but can then appear in this list.
Path or URL prefix for attachments	Items that cannot be stored directly in a CSV file (such as photos or signatures) are saved separately and the path to that file is stored. Enter the path here or a prefix for the URL.
Override root output folder	As detailed above, most outputs from magic5 are stored in the "Root Output Directory", directly or as sub-folders. CSV files can be stored elsewhere (ie outside the Root Directory) by entering an alternative here.

Automatically release to customer

This action requires Description and Condition which are discussed above.

E-mail notification (no attachments)

This action is the same as "E-mail a PDF version of the report" in that it allows for e-mail notifications to be sent to various people. However, no attachment is sent with the e-mail.

Device actions

Actions are triggered on the device When a report is finished on the device and before it is sent to the magic5 server. These actions allow things like direct e-mailing from the device and printing.

E-mail documents from device

This action allows the creation and e-mailing of Word-compatible and Excel-compatible documents directly from the device.

Output directory	The directory that will contain the PDF output files. Note that this directory will be underneath the “Root Output Directory”, so here you simply need to specify the relative path (eg. “XYZ System Output”). Any folder specified does not have to exist. This field allows “Report processing variables”.
Output RTF (Word-compatible document)	Tick this box if you wish to create a .rtf document for e-mailing or copying onto a PC or network. RTF (“Rich Text Format”) documents are compatible with Microsoft Word and can be viewed and edited using Word.
Template file name (.rtf)	The format of the generated .rtf file can be specified using a template file. This allows you to create documents with your own logos, company details and general formatting. magic5 supplies a basic format template called Template.rtf (not to be confused with “templates” which define the look of forms on the device). Template.rtf outputs all items within the form in a simple way. If you wish to create your own format of document then you can create your own file, for example, MyTemplate.rtf and specify this file name to be used when creating the output file.
Output CSV (Excel-compatible document)	Tick this box if you wish to create a .csv document for e-mailing or copying onto a PC or network. CSV (“Comma Separated Variable”) documents are compatible with Microsoft Excel and can be viewed and edited using Excel.
Don’t automatically Send/Receive e-mails	Allows documents to be created but not e-mailed. Use this option if you wish to have a copy of a completed forms which you can copy off the device without using e-mail.
E-mail address to send report to	Enter the e-mail address of the person you wish the report to be sent to. This should be a valid SMTP e-mail address such as somebody@company.com
E-mail all addresses specified in ‘E-mail Address’ template items	If you have an “e-mail address” item within your template (allowing the user to input a customer’s e-mail address for example) then selecting this option will cause the report to be e-mailed to addresses specified in this way.
E-mail service to use	With magic5 running on a Device, this specifies the e-mail service to be used when sending e-mails. This is the name given to the e-mail account (eg. O2, Hotmail, BT Internet) not the e-mail address (eg. pdauser@o2.com). If no value is specified then magic5 will use the first e-mail account that it finds. Note that the first e-mail account is often “Outlook E-mail” – this account will allow you to send the generated e-mails once the Device is connected to a PC but won’t allow sending “over the air” via the phone network. With a PC-based version of magic5, this field gives the e-mail address to send messages from.
Subject line of e-mail	Enter the subject line of the e-mail
Text of e-mail	Enter the body of the e-mail
Save attachments to ‘shared’ folder for synchronising to desktop	For Device-based versions of magic5 this specifics that generated documents will be saved in the “My Documents” folder. This folder can be set up to be automatically synchronised to a PC using ActiveSync and so provides a simple method to copy documents off the Device. If this option is not selected then documents will be created within magic5’s Output folder on the Device.

Run custom code on the device

This action allows the running of a custom program when a form is released on the Device.

Assembly and class	The assembly and class name containing the custom code in the standard format. For example, MyFileName,MyClass.ClassName
Method name	The method name to run. For example, UpdateMyBitsAndPieces

Print document from device

This action allows a document to be printed when a form is released on the Device, which has to be manually triggered so the "Allow user to choose to run this action" should be ticked.

Custom print format

The assembly and class name that contains the appropriate print format. For example, MyPrintFile,MyClass.PrintController.

This format has to be created at implementation - discuss this with Cadence Computing Limited prior to installation.

Spell check on device

This action allows a document to be spell checked when a form is released on the Device.

Application name (as shown in ‘Remove Programs’)	For Device forms, this option allows a third party program to be specified as a spell checker for forms. For example, PhatWare PhatSpell
File name to run	The name of the spell checking application. For example, PhatSpell.exe

Device workflow

This Action allows a further form to be sent for completion on the device, conditional on whether the state of the original form (completed or not). This is a useful tool for the circumstance where, for instance, an engineer might find that the job they have been scheduled to do requires further parts - they can flag the job as incomplete, prompting the creation of a Parts Request Form and, on receipt of the parts, can continue and complete the form, prompting a Job Sign-off Form.

Next form in workflow for completed jobs	Select from a list of available templates that appear in the drop-down box.
Next form in workflow for incomplete jobs	Select from a list of available templates that appear in the drop-down box.
Unique name of item to keep for workflow	Enter the unique name of any items that you wish to carry forward onto either complete or incomplete job forms

Select appropriate forms from the drop-down lists on the Main tab of this Action - these forms, therefore, need to be devised in advance.

With careful forethought this is a powerful action which can guide the mobile device user through complicated paperwork.

Device update customer flag

This Action enables special customer data to be updated dependent on pre-defined conditions.

Condition	As described above for serverside conditions
Name of Flag	Enter flag name as created at implementation - contact Cadence Computing Limited support for more information
Value of Flag	Appropriate value to assign to the flag when the conditions above are met - eg if customer is spending over £200 the percentage discount flag may be set to 10. Ensure that this value is in the correct format for the data you expect to be held - ie if the flag expects a 'yes/no' response, do not enter numbers at this point.